home *** CD-ROM | disk | FTP | other *** search
/ Nebula 1 / Nebula One.iso / Graphics / Multimedia / Movie3.0 / Source / xanim / xanim.readme < prev    next >
Encoding:
Text File  |  1995-07-03  |  31.9 KB  |  818 lines

  1.  
  2. !!!!!!  This is the NEXTSTEP modified X-less version
  3. !!!!!!  all changes (c) 7-3-95 Andreas Windemuth
  4. !!!!!!  It will not do what is claimed in this file.
  5. !!!!!!  It goes with Movie.app. Use at your own risk!
  6.  
  7. XAnim Rev 2.68.5  23Aug94
  8.  
  9. COMPILING ON UNIX Systems (SunOS,Solaris,HP/UX,DG/UX,AIX,
  10.                Linux,Ultrix,OSF/1,etc)
  11.  
  12.  
  13.   If you have Imake on your system you can type
  14.  
  15.     xmkmf
  16.  
  17.   which should produce a Makefile from the Imakefile. Then
  18.   you can type:
  19.  
  20.     make xanim
  21.   
  22.   If this doesn't work you can copy Makefile.unx to Makefile.
  23.   Edit the Makefile and specify where the X11 includes and 
  24.   X11 libraries are on your particular machine. Then type
  25.  
  26.     make xanim
  27.  
  28.   NOTE: That in the Imakefile, XCOMM is used as a comment. This
  29.   is recommended by X11R6, but may break older revs. To fix,
  30.   simply replace every occurence of "XCOMM" with "#" in the
  31.   Imakefile. See top of Imakefile for more details.
  32.  
  33.  
  34. COMPILING ON VMS/AXP Systems
  35.   The files make.com and xanimXX.opt are provided for VMS users.
  36.   make.com should correctly detect wether you're running
  37.   DECWindows XUI or DECWindows MOTIF(revs 1.1 and 1.2) and use
  38.   the appropriate xanimXX.opt file.
  39.  
  40.   If you use the VMS MMS (or "make") facility, then a descript.mms
  41.   file is provided.
  42.  
  43.   NOTE: since VMS is case insensitve, all options to xanim must be
  44.   enclosed in double quotes in order for them to be proper recognized.
  45.   Example:
  46.         xanim "+bCn" anim1 anim2
  47.  
  48.  
  49. HOW TO USE XANIM
  50. The following is a copy of the man page with examples at the end.
  51.  
  52. SYNOPSIS
  53.      xanim [ +Vnum ] [ +Aaopts ]  [  +Ccopts  ]  [  +Ggopts  ]  [
  54.           +Mmopts  ] [ +Ssopts ] [ +opts ] animfile [ [ +opts ] [
  55.           animfile ] ... ]
  56.  
  57. DESCRIPTION
  58.      XAnim is a program that can display  animations  of  various
  59.      formats on systems running X11. XAnim currently supports the
  60.      following animation types:
  61.  
  62.       +  FLI animations.
  63.       +  FLC animations.
  64.       +  IFF animations.  The  following  features  are  sup-
  65.          ported:
  66.            -> Compressions 3,5,7,J(movies) and l(small L).
  67.            -> Color cycling during single images and anims.
  68.            -> Display Modes: depth 1-8, EHB, HAM and HAM8.
  69.       +  GIF87a and GIF89a files.
  70.            -> single and multiple images supported.
  71.            -> GIF89a animation extensions supported.
  72.       +  GIF89a animation extension support.
  73.       +  a kludgy text file listing gifs and  what  order  to
  74.          show them in.
  75.       +  DL animations. Formats 1 and 2.
  76.       +  Amiga PFX(PageFlipper Plus F/X) animations.
  77.       +  Amiga MovieSetter animations(For those Eric Schwartz
  78.          fans).
  79.       +  Utah Raster Toolkit RLE images and anims.
  80.       +  AVI animations. Currently supported are
  81.            ->*IBM Ultimotion     (ULTI) depth 16.
  82.            -> Microsoft Video 1  (CRAM) depth 8 and 16.
  83.            -> SuperMac Cinepak   (CVID) depth 24.
  84.            -> Uncompressed       (RGB ) depth 8
  85.            -> Run length encoded (RLE8) depth 8.
  86.       +  Quicktime Animations.  The  following  features  are
  87.          supported:
  88.            -> Uncompressed     (RAW ) depth 8.
  89.            -> Apple Graphics   (RLE ) depth 1,8,16 and 24.
  90.            -> Apple Animation  (SMC ) depth 8.
  91.            -> Apple Video      (RPZA) depth 16.
  92.            -> SuperMac Cinepak (CVID) depth 24.
  93.            -> ???      YUV2    (YUV2) depth 24.
  94.            -> Supports multiple video trak's.
  95.            -> Supports animations with multiple codecs.
  96.            -> Supports single-fork and separate .rsrc and .data forks.
  97.       +  any combination of the above  on  the  same  command
  98.          line.
  99.  
  100. ---------------------------------------------------------------------------
  101. * The following copyright applies to all Ultimotion segments of the code:
  102.   
  103.   "Copyright International Business Machines Corporation 1994, All rights
  104.    reserved. This product uses Ultimotion(tm) IBM video technology."
  105. ---------------------------------------------------------------------------
  106.  
  107.      XAnim also provides various options that allow the  user  to
  108.      alter colormaps, playback speeds, looping modes and can pro-
  109.      vide on-the-fly scaling of animations with the mouse.
  110.  
  111. OPTIONS
  112.      A + will generally turn an option on and a -  will  turn  an
  113.      option  off.   This  can  be  reversed at compile time. (see
  114.      xanim_config.h).
  115.  
  116.      In each SubMenu, the options can be  run  together  with  no
  117.      intervening spaces. In the list of SubMenu options presented
  118.      below, the first letter given is the letter  that  specifies
  119.      the  SubMenu  and  should NOT be repeated if several SubMenu
  120.      options are to be run together.
  121.  
  122.      For example,  "+Cn  +Cs10  +CF4"  can  also  be  written  as
  123.      "+Cns10F4" or "+CF4s10n".
  124.  
  125.      A + or a - within a SubMenu will be an exit from  that  sub-
  126.      menu.   Options  will  affect  all  animations following the
  127.      invocation of that option. Some options may  be  changed  in
  128.      between animations without affecting previous animations.
  129.  
  130.      In the following sections,  an  "num"  represents  an  integer
  131.      number and an "fnum" represents a floating point number. Don't
  132.      include the double quotes. If a floating point number is of an 
  133.      integer amount, the "." need not be specified. There should be
  134.      no spaces between the option and the numbers.
  135.  
  136.      copts SubMenu for Color Options
  137.  
  138.       +C1        Create a colormap from the  first  frame  of  a
  139.             TrueColor  anim  and  then  remap the remaining
  140.             frames to this colormap. This  can  potentially
  141.             add  significant time to the startup of an ani-
  142.             mation but usually results  in  better  colors.
  143.             The  animation  needs  to  be buffered for this
  144.             option to work.  Not  valid  for  TrueColor  or
  145.             DirectColor displays(nor is it needed).
  146.  
  147.       +C3        Convert TrueColor  anims  to  332(StaticColor).
  148.             TrueColor  anims  are  animations  that provide
  149.             separate RGB info for each pixel,  rather  than
  150.             each  pixel being an index into a global color-
  151.             map. AVI(16bit CRAM), QT(RPZA and RLE depth  16
  152.             and  24)  and URT RLE 24 bit anims are examples
  153.             of TrueColor anims. This option is ignored  for
  154.             TrueColor or DirectColor displays.
  155.  
  156.       +CA         Create  a  colormap  from  each  frame   of   a
  157.             TrueColor  anim.  This  can  be  useful  if the
  158.             colors radically change during  the  course  of
  159.             the  animation.  This can take a VERY,VERY long
  160.             time at start up. Animation must  be  buffered.
  161.             This   option   is  ignored  for  TrueColor  or
  162.             DirectColor displays.
  163.  
  164.       +Ca         Remap all images to  single  new  cmap  created
  165.             from all of the colormaps.
  166.  
  167.       +Cd         Use Floyd-Steinberg  dithering  if  needed  for
  168.             non-monochrome  displays.   This  will  cause a
  169.             reduction in playback speed.
  170.  
  171.       +Cf         Forcibly remap to all  frames  to  1st  frame's
  172.             cmap.
  173.  
  174.       +CF0          Turns off CF4 option.
  175.  
  176.       +CF4          This option samples the colors of true color
  177.             animations ahead of time and forms a color
  178.             lookup table.  Beats the just truncating to a
  179.             RGB 332 color table and IMHO beats dithering.
  180.             See the +s option below(also in copts submenu).
  181.  
  182.       +Cg         Convert TrueColor anims  to  gray  scale.  This
  183.             option is ignored for TrueColor and DirectColor
  184.             displays.
  185.  
  186.       +Ch         Use histogram to aid in color  reduction.  His-
  187.             trogramming  is  only  done  on frames that are
  188.             buffered.
  189.  
  190.       +Cm         This option is currently needed if you want  to
  191.             dither  TrueColor anims to a 332 colormap. Ani-
  192.             mation must be buffered.  Typically  +bC3dm  is
  193.             the  option  to  use. This can take a VERY long
  194.             time at start up.
  195.  
  196.       +Cn         Don't create new colormap but instead  allocate
  197.             colors from the X11 Display's default cmap.
  198.  
  199.       +Cs"num"    This is the number of frames the +CF4 option looks
  200.             at ahead of time. More frames potentially yields
  201.             better colors results, but takes more time at
  202.             start up.  default is 5.
  203.  
  204.      gopts SubMenu for Gamma Options
  205.  
  206.       +Ga"fnum"    Set gamma of animation to be displayed.
  207.  
  208.       +Gd"fnum"    Set gamma of display. 1.0 is no change. gamma's
  209.             greater  than 1.0 typically brighten the anima-
  210.             tion.
  211.  
  212.      mopts SubMenu for Median-Cut Quantization Options
  213.  
  214.       +Ma        compute box color from average of box.
  215.  
  216.       +Mc        compute box color as center of box.
  217.  
  218.       +Mb"num"    Truncate rgb to "num" bits before quantizing.
  219.  
  220.      sopts SubMenu for Scaling Options
  221.  
  222.       +Si        Half the  height  of  IFF  anims  if  they  are
  223.             interlaced.(Not  completely  reliable since not
  224.             all IFF anims correctly identify themselves  as
  225.             interlaced).
  226.  
  227.       +Sn        Prevents X11  window  from  resizing  to  match
  228.             animations's size.
  229.  
  230.       +Sr        Allow user to  resize  animation  on  the  fly.
  231.             Enlarging an animation can greatly reduce play-
  232.             back speed depending on the power of the cpu.
  233.  
  234.       +Ss"fnum"    Scale the size  of  animation  by  "fnum"  before
  235.             displaying.
  236.  
  237.       +Sh"fnum"    Scale the horizontal size of the  animation  by
  238.             "fnum" before displaying.
  239.  
  240.       +Sv"fnum"    Scale the vertical size  of  the  animation  by
  241.             "fnum" before displaying.
  242.  
  243.       +Sx"num"    Scale the animation to have  width  "num"  before
  244.             displaying.
  245.  
  246.       +Sy"num"    Scale the animation to have height  "num"  before
  247.             displaying.
  248.  
  249.       +Sc        Copy display scaling factors to display buffer-
  250.             ing factors.
  251.  
  252.       +SS"fnum"    Scale the size of the animation by "fnum"  before
  253.             buffering it.
  254.  
  255.       +SH"fnum"    Scale the horizontal size of the  animation  by
  256.             "fnum" before buffering it.
  257.  
  258.       +SV"fnum"    Scale the vertical size  of  the  animation  by
  259.             "fnum" before buffering it.
  260.  
  261.       +SX"num"    Scale the animation to have  width  "num"  before
  262.             buffering it.
  263.  
  264.       +SY"num"    Scale the animation to have height  "num"  before
  265.             buffering it.
  266.  
  267.       +SC        Copy buffer scaling factors to display  scaling
  268.             factors.
  269.  
  270.      Normal Options
  271.  
  272.       +b        Uncompress and buffer images before displaying.
  273.             This only applies to AVI,QT, IFF,FLI,FLC anima-
  274.             tions. The rest(GIF87a,GIF89a,DL,PFX  and  RLE)
  275.             are currently always uncompressed and buffered.
  276.             This is cleared by the +f option.
  277.  
  278.       +B        Used X11 Shared Memory(if present)for unbuffered
  279.             animations only.(This is mutually exclusive with
  280.             +b above).
  281.  
  282.       +f        Don't load anim into memory, but read each sec-
  283.             tion  only  when needed. This is supported only
  284.             for AVI,QT,IFF,FLI  and  FLC  animations.  This
  285.             option  is cleared by the +b option. This saves
  286.             memory at the cost of speed.
  287.  
  288.       +c        let xanim know that iff anim  is  a  nonlooping
  289.             one.
  290.  
  291.       +d"num"    debug switch. "num" can be from 0(off) to 5(most)
  292.             for level of detail.
  293.  
  294.       +F        Floyd-Steinberg dithering when needed.
  295.  
  296.       +j"num"    "num"  is  the  number  of  milliseconds  between
  297.             frames.  if  0  then  the time specified in the
  298.             animation is used for timing purposes.
  299.  
  300.       +l"num"    loop animation "num" number of times before  mov-
  301.             ing on to next animation.
  302.  
  303.       +lp"num"    ping-pong animation "num" number of times  before
  304.             moving on to next animation.
  305.  
  306.       +N        don't display images. Useful for benchmarking.
  307.  
  308.       +o        turns    on    certain    optimizations.    See
  309.             xanim.readme.
  310.  
  311.       +p        Use Pixmap instead of Image in X11. This option
  312.             has    no    effect   if   the   animation   is
  313.             buffered(either  by  default  or  with  the  +b
  314.             option).
  315.  
  316.       +r        Allow color cycling for IFF single images.
  317.  
  318.       +R        Allow color cycling  for  IFF  anims.  (default
  319.             should be off)
  320.  
  321.       +T0        Title option 0. Title is just XAnim.
  322.  
  323.       +T1        Title option 1. Title  is  current  anim  name.
  324.             When  anim is stopped, the current frame number
  325.             is included.
  326.  
  327.       +T2        Title option 2. Title is current anim name  and
  328.             current frame number.
  329.  
  330.       +v        Verbose mode. Gives some information about ani-
  331.             mation such as size, number of frames, etc.
  332.  
  333.       +V"num"    Select X11 Visual to use when displaying anima-
  334.             tion.  The  "num"  is  obtained  by  using the +X
  335.             option of xanim.
  336.  
  337.       +Vclass    Select the best X11 Visual of Class class  when
  338.             displaying  the  animation. class can be anyone
  339.             of the following strings and is  case  insensi-
  340.             tive. (ie StaTicGraY is same as staticgray).
  341.  
  342.             staticgray    Select best StaticGray Visual.
  343.             grayscale     Select best GrayScale Visual.
  344.             staticcolor   Select best StaticColor Visual.
  345.             pseudocolor   Select best PseudoColor Visual.
  346.             truecolor     Select best TrueColor Visual.
  347.             directcolor   Select best DirectColor Visual.
  348.  
  349.       +X        X11 verbose mode. Display information about the
  350.             support X11 visuals.
  351.  
  352.       +Ze        XAnim will exit after playing  through  command
  353.             line once.
  354.  
  355.       +Zp"num"    XAnim pause at frame "num" and then wait for user
  356.             input.  Several  pauses  may be specified. Each
  357.             group of pauses will only affect the  animation
  358.             immediately following them on the command line.
  359.             Pauses will occur at least once.
  360.  
  361.  
  362.  
  363. WINDOW COMMANDS
  364.      Once the animation is up and running there are various  com-
  365.      mands  that  can  be entered into that animation window from
  366.      the keyboard.
  367.  
  368.      q         quit.
  369.  
  370.      Q         Quit.
  371.  
  372.      g         Stop color cycling.
  373.  
  374.      r         Restore original Colors(useful after g).
  375.  
  376.      w         Restore original window size(useful  after  resiz-
  377.            ing).
  378.  
  379.      <space>   Toggle. starts/stops animation.
  380.  
  381.      ,         Single step back one frame.
  382.  
  383.      .         Single step forward one frame.
  384.  
  385.      <         Go back to start of previous anim.
  386.  
  387.      >         Go forward to start of next anim.
  388.  
  389.      m         Single step back one frame staying within anim.
  390.  
  391.      /         Single step forward one frame staying within anim.
  392.  
  393.      -         Increase animation playback speed.
  394.  
  395.      =         Decrease animation playback speed.
  396.  
  397.      0         Reset animation playback speed to original values.
  398.  
  399. MOUSE BUTTONS
  400.      Once the animation is up and running the mouse buttons  have
  401.      the following functions.
  402.  
  403.      <Left_Button>
  404.            Single step back one frame.
  405.  
  406.      <Middle_Button>
  407.            Toggle. starts/stops animation.
  408.  
  409.      <Right_Button>
  410.            Single step forward one frame.
  411.  
  412. BUFFERING, PIXMAPS and READ_FROM_FILE Options
  413.      XAnim by default will read the entire animation into memory.
  414.      DL,  PFX,  Moviesetter,  GIF  or URT RLE type animations are
  415.      always uncompressed  and  stored  in  memory  as  individual
  416.      images.
  417.  
  418.      For  the  AVI,  QT,  IFF,  FLI/FLC  animations,   only   the
  419.      compressed   delta   is   stored.   These  deltas  are  then
  420.      uncompressed each time they need to be displayed. The buffer
  421.      option(+b)  may  be used to potentially speed up playback by
  422.      uncompressing and storing these images ahead  of  time.  But
  423.      more memory is used up in the process.
  424.  
  425.      When an XPutImage is called, the image typically gets copied
  426.      twice,  once to memory and then from there onto the display.
  427.      A pixmap is directly copied onto  the  display  without  the
  428.      first  copy.  This is why it is sometimes much faster to use
  429.      the pixmap option(+p).  Each image isn't  converted  into  a
  430.      pixmap until the first time it is displayed. This is why the
  431.      first loop of an animation using this  option  is  sometimes
  432.      slower  than  subsequent  loops. While the pixmap option may
  433.      improve playback speed, it will slow things down if  on-the-
  434.      fly  scaling needs to be performed. This is because XAnim no
  435.      longer has direct access to the image and  needs  to  get  a
  436.      copy of it before it can be scaled.
  437.  
  438.      The read from file option(+f) causes xanim not to store  the
  439.      compressed  deltas in memory. Instead as each image is to be
  440.      displayed, xanim reads the  corresponding  compressed  delta
  441.      from  the  file, expands it and then displays it. While this
  442.      can dramatically cut down on  memory  usage,  the  necessary
  443.      reads  from  disk(or whatever) can slow down playback speed.
  444.      XAnim still needs to allocate one  to  three  image  buffers
  445.      depending  on  the type of animation and the scaling options
  446.      used. This option is only supported for AVI, QT, FLI/FLC and
  447.      IFF  animations.  The  BODY  chunk  of IFF animations is not
  448.      included in this. As a result, an IFF animation that is made
  449.      up  of  several  BODY chunks will not currently benefit from
  450.      this option.
  451.  
  452.  
  453. SCALING Options
  454.      There are two sets of scaling options. One set, the  display
  455.      scaling factors,  affects the size of the animation as it is
  456.      displayed. The other set, the buffer scaling factors, affect
  457.      the   size   of   the   images   as   they   are  stored  in
  458.      memory(buffered). The buffer  scaling  factors  only  affect
  459.      animations  that  are  buffered  and can greatly increase or
  460.      decrease memory usage.
  461.  
  462.      These two sets are completely independent of each other. You
  463.      can  set  the  buffer scaling factors to 20 times the normal
  464.      animation size and not affect the size at which that  anima-
  465.      tion  is  displayed.  The  images are stored at 20 times the
  466.      normal size(and at 400 times the memory usage), but then get
  467.      scaled  back  down  to  normal  size before being displayed.
  468.      NOTE: that an animation must be buffered in  order  for  the
  469.      buffer scaling factors to have any affect on it. The display
  470.      scaling factors affect all animations.
  471.  
  472.      You can create pixellation like  affects  by  buffering  the
  473.      animation  at  1/8 it's normal size, but keeping the display
  474.      scaling factors at the original size. (IE  "xanim  +bSS0.125
  475.      anim.anim").
  476.  
  477.      Many times it's faster to store  and  display  an  animation
  478.      with large dimensions at half-size. The option "+bSS0.5C" or
  479.      "+bSS0.5s0.5" both will accomplish this. To save memory, you
  480.      could  even store the animation at half size and yet display
  481.      it at full size. "+bSS0.5" will accomplish this.
  482.  
  483. FORWARDS, BACKWARDS and OPTIMIZATION.
  484.      Many type of animations(FLI/FLC/IFF/some AVI  and  QTs)  are
  485.      compressed  with  forward  playback in mind only. Each delta
  486.      only stores the difference between the current frame and the
  487.      previous frame. As a results, most of these animations don't
  488.      display correctly when played backwards.  Even when buffered
  489.      up, these may not work, since XAnim only stores the smallest
  490.      rectangle that encompasses the  changes  from  the  previous
  491.      frame.  You  can  force  XAnim  to store the entire frame by
  492.      specifying the "-o" option to turn  this  optimization  off.
  493.      This will most likely use more memory and slow down the ani-
  494.      mation, since more of the image needs to  be  stored  and/or
  495.      displayed.
  496.  
  497. COLOR OPTIONS
  498.      Most of this will be a TBD for a future rev and what's  here
  499.      might be sketchy, incomplete or just plain confusing.
  500.  
  501.      TrueColor and DirectColor displays don't need to worry about
  502.      most of these options, as the animations can be displayed in
  503.      their original colors(ignoring monitor variations etc). How-
  504.      ever,  TrueColor  and  DirectColor  displays  can't  display
  505.  
  506.      animations that employ color cycling  techniques  where  the
  507.      colormap  changes  from  frame  to frame.  DirectColor could
  508.      potentially support this, but not TrueColor.
  509.  
  510.      For the rest of the displays, the problem  becomes  matching
  511.      the  colors in the animations to the available colors of the
  512.      Display.  For  most  PseudoColor  displays  this  means  256
  513.      colors.  Many  of  which are already in use by various other
  514.      programs. XAnim defaults to creating it's own  colormap  and
  515.      using  all  the  colors  from  that. The window manager then
  516.      installs this new colormap, whenever the  mouse  pointer  is
  517.      inside  the  XAnim  animation  window(Sometimes  a  specific
  518.      action is required to change the ColorMap Focus, like click-
  519.      ing  in the window or pressing a specific key). In any case,
  520.      this action usually causes  all  the  other  colors  on  the
  521.      screen  to  be  temporarily  "messed-up"  until the mouse is
  522.      moved out of the animation window. The  alternative,  is  to
  523.      use  the  "+Cn"  option.  Now XAnim tries allocating all the
  524.      colors it needs from the current colormap. If it can't get a
  525.      certain color, then XAnim choose one that is "close" to this
  526.      certain color. Close is completely arbitrary. The  animation
  527.      is  now displayed in colors that are different than the ori-
  528.      ginal colors. This difference may or may not be noticeable.
  529.  
  530.      Another big problem is when the animations are what I called
  531.      TrueColor animations. Where each pixel is stored as RGB tri-
  532.      plets. For example, AVI 16 bit CRAM animations.  Each  pixel
  533.      has  5  bits of Red, 5 bits of Green and 5 bits of Blue info
  534.      associated with it. This means there  can  be  up  to  32768
  535.      unique  colors  in  each  image.  And  on  most  PseudoColor
  536.      displays we can only display 256 unique colors. Beside  get-
  537.      ting  better  displays,  what  can  we do? XAnim defaults to
  538.      truncating the RGB information from 555 to 332. That is to 3
  539.      bits  of  Red,  3  bits of Green and 2 bits of Blue. Less on
  540.      Blue because the human eye is  more  sensitive  to  Red  and
  541.      Green than Blue.  This 332 colormap happens to be 256 colors
  542.      in size, which nicely fits  in  with  our  display.  If  our
  543.      display  only  had  64 colors, then XAnim is smart enough to
  544.      truncate things down to 222. Now the problem is  the  colors
  545.      of the displayed anim are noticeably different than the ori-
  546.      ginal colors.  Typically you  can  see  color  banding  etc.
  547.      While  this  is fine to get a feel for the animation, we can
  548.      do better. One of the solutions XAnim  currently  offers  is
  549.      the "+bC1" option. What this does is choose the the best 256
  550.      colors from the first image  of  the  animation.  Then  each
  551.      pixel  of  each subsequent image is remapped to one of these
  552.      256 colors.  This takes up some CPU time up front  and  more
  553.      memory since each image needs to be buffered, but results in
  554.      a colors that are closer to the originals.  Another  option,
  555.      "+bCA",  chooses  the  best  256  from  each image, then 256
  556.      colors from all these colormaps  are  chosen  as  the  final
  557.      colormap.   This  is useful if the colors in the first image
  558.      aren't representative of the rest of the animation. This can
  559.      be  very  slow.  Another  option  that is supported, but not
  560.      really optimized for yet is "+bC3dm". This causes  XAnim  to
  561.      use  a  332 colormap and then apply a Floyd-Steinberg dither
  562.      algorithm to each image.  Currently this is very slow.  Dif-
  563.      ferent  dithers(like Ordered) and better optimizations might
  564.      speed this up  in  future  revs.  In  general,  handling  of
  565.      TrueColor animations in XAnim needs to be improved.
  566.  
  567.      Another scenario where colors need to be remapped,  is  when
  568.      several  images  or animations with different colormaps need
  569.      to be displayed.  Changing the colormap usually  results  in
  570.      an annoying flicker. One solution to this is to remap all of
  571.      the images/animations to the same colormap. The "+Ca" option
  572.      chooses  the  best  colors  from  all the colormaps and then
  573.      remaps all the images to it. The "+Cf" option, simply remaps
  574.      everything  to the first colormap.  The "+Ch" option is use-
  575.      ful when an animation's colormap specifies a lot  of  colors
  576.      that aren't used. XAnim looks through each buffered image of
  577.      the animation and makes a histogram of the  useage  of  each
  578.      color.  This  information  is then used to weedout unused or
  579.      rarely used colors.
  580.  
  581. QUICKTIME ANIMATIONS
  582.      Quicktime animations are  usually  stored  in  two  separate
  583.      files.  One is call a data fork and ends with a ".data". The
  584.      other is a resource fork and ends in  a  ".rsrc".  Sometimes
  585.      these  animations  are in a "flattened" format, where every-
  586.      thing is put into one file. There's no standard naming  for-
  587.      mat for these types of files.
  588.  
  589.      For example, if you have a quicktime animation  made  up  of
  590.      two  files  named:  "spin.rsrc"  and  "spin.data",   you can
  591.      display them using Xanim with either of the  following  com-
  592.      mands  "xanim  spin"  or  "xanim spin.rsrc".  XAnim is smart
  593.      enough to add/modfiy the  ".rsrc"  and  ".data"  endings  as
  594.      needed.
  595.  
  596.      If you use AUFS from the Columbia  Appletalk  Package,  then
  597.      Macintosh  files have their data fork stored in the expected
  598.      place, and the resource fork is in a file with the same name
  599.      in a  .resource subdirectory. Therefore, if the data fork is
  600.      in "spin", and the resource fork isin  ".resource/spin", the
  601.      movie can be displayed with "xanim spin".
  602.  
  603.      For "flattened" quicktime animations, you  need  to  specify
  604.      the entire file name.
  605.  
  606.      NOTE: XAnim may not support all SMC or RPZA quicktime anima-
  607.      tions. It'll print "unknown code variation XX" to the screen
  608.      as it encounters these and move on to the next image of that
  609.      animation.
  610.  
  611.  
  612. EXAMPLES:
  613.     To display a single animation:
  614.  
  615.         xanim iff3.anim
  616.  
  617.     To display a nonlooping IFF animation:
  618.  
  619.         xanim +c iff3.anim
  620.  
  621.     To display A.fli 3 times, B.anim and C.movie 2 times each and D.fli
  622.     once before repeating:
  623.  
  624.         xanim -l3 A.fli -l2 B.anim C.movie -l1 D.fli
  625.  
  626.     To see A.anim real slow(2 seconds for each frame):
  627.  
  628.         xanim +j2000 A.anim
  629.  
  630.     To display title image for a while then run an animation at
  631.     normal speed:
  632.  
  633.         xanim +j2000 title.gif +j0 anim.gifanim
  634.  
  635.  
  636. A series of GIF's can be displayed as:
  637.  
  638.     xanim im_0.gif im_1.gif im_2.gif ... im_36.gif
  639.  
  640.  or
  641.  
  642.     xanim im_*.gif
  643.  
  644.  or
  645.  
  646.     xanim im.txt
  647.  
  648.  or
  649.  
  650.     xanim im.gifanim
  651.  
  652. where im.txt is a txt file(a list of images, see xanim.doc for more details).
  653. and im.gifanim is one gif file composed of im_0.gif through im_36.gif.
  654. (see txtmerge to create a single gif file from a txt file).
  655.  
  656. X11 Notes:
  657. --------------------------------------
  658.  I. X11 Server Options
  659.  
  660.    When XAnim opens the display it passes the argument list to X11 which
  661.    then filters off the arguments it recognizes. XAnim won't even see these
  662.    arguments(which is sometimes a problem). For instance
  663.  
  664.    xa -geom =+100+100 skier.fli
  665.  
  666.    will play the anim skier.fli at pos <100,100> on the X11 screen.  Or
  667.  
  668.    xa -display nantucket:0.0 skier.fli
  669.  
  670.    will display the anim skier.fli on the machine nantucket's display.
  671.  
  672.    Sometimes this is a problem, because a valid XAnim option is stripped by the
  673.    X11 server. For instance if +r was being stripped, then use ++r instead.
  674.    Same goes with -r. Use --r instead if you believe it's being filtered
  675.    by X11.
  676.  
  677. Machine Specific and Compiler Notes:
  678. --------------------------------------
  679.  Some PC's need you to uncomment the line below in Makefile.
  680.  #XA_INET_LIB = -linet
  681.  
  682.  Depending on your window manager(mwm,uwm,olwm,twm etc), you might
  683.  want to have XAnim do a XInstallColormap. This shouldn't be necessary
  684.  for most workstations and can cause core dumps on some PCs.
  685.  There are usually user selectable options for each window manager
  686.  that selects the colormap focus policy(pointer,fixed,explicit etc).
  687.  Use -DNO_INSTALL in Makefile if you DON't want XAnim to install
  688.  the colormap.
  689.  
  690.  Some X11's don't have support for multiple visuals.  An executable
  691.  compiled with such an X11 will not be able to correctly run on a
  692.  machine that does supports multiple visuals even if they're binary
  693.  compatible.
  694.  
  695.  Hugh D.R. Evans has supplied make.com, xanim.opt and added VMS defines
  696.  so that VMS users may compile and run XAnim. Rick Dyson has provided
  697.  the descript.mms file and some VMS fixes. John Kneitz has also
  698.  provide some VMS fixes and suggestions.
  699.  
  700. And Yet More Notes about Quicktime Animations
  701. ---------------------------------------------
  702.         NOTES ON QUICKTIME ANIMATIONS WITH XANIM
  703.  
  704.   (these are just my notes and may contain some inconsistencies.
  705.    There's currently some question about the true meaning of
  706.    "flatten". It might just mean taking a quicktime file and
  707.    replacing a references to another files with those files
  708.    themselves.  But lately many people use it to mean collapsing
  709.    the *.data and *.rsrc forks into one *.data fork for export
  710.    to a non-mac computer. - Mark)
  711.  
  712.  
  713.    EXTRACTING Quicktime Animations
  714.  
  715.     Typically you will obtain the quicktime animations that have
  716.     been archived and then binhex'd. If the file you have ends
  717.     in a .hqx, then you need to run hexbin on it ("hexbin anim.hqx").
  718.     This will create a *.bin file(not necessarily anim.bin, it
  719.     could be anything.bin. The actual name is contained within
  720.     the *.hqx file).  
  721.  
  722.     If the file you have ends in a .bin or you've just hexbin'd a file, 
  723.     now you need to unpack it. In other words extract the files that
  724.     are contained within it. These files can be programs/documents/
  725.     animations/images etc. They're not necessarily quicktime animations.
  726.  
  727.     There is a program called macunpack that should be used to
  728.     accomplish this. You need to use the -f option, I recommend
  729.     the -lv options as well. (ie "macunpack -flv file.bin")
  730.  
  731.     Macunpack doesn't support certain DiskDoubler or Stuffit Deluxe
  732.     archives. There is no unix/pc program that I know of that does(except 
  733.     for the Mac). In this case your only choice is to get a hold of a 
  734.     Macintosh computer and someone who knows how to use it and
  735.     hopefully some method of transferring files to/from it.
  736.  
  737.     Once you've unpacked everything, you should have three files,
  738.     a *.info, a *.rsrc and a *.data. You can delete the *.info file.
  739.     XAnim doesn't need or use it.
  740.  
  741.     The quicktime animation is made up of BOTH the *.rsrc and the
  742.     *.data files and therefore XAnim needs BOTH the *.rsrc and the 
  743.     *.data in order to recognize and display the animation.
  744.   
  745.     The only exception to this is if the animation has been "flattened".
  746.     Essentially, all that this means is that the .rsrc and .data files
  747.     were merged into one file for export to a non-mac computer.
  748.     This file doesn't have any real naming conventions, but it is
  749.     usually something like .mov, .mv, .qt, etc(it is never .bin or .hqx). 
  750.     And it is rarely .data. If XAnim can't play it, then it's 95%
  751.     likely to be a *.data fork(that's missing a *.rsrc fork) and not
  752.     a flattened quicktime animation.
  753.  
  754.     Macunpack and hexbin can be found in the macutil archive. They
  755.     are available at the following locations:
  756.  
  757.         sumex-aim.stanford.edu:/info-mac/unix/macutil-20b1.shar
  758.         ftp.cwi.nl:/pub/macutil2.0b3.shar.Z
  759.         solaris.ims.ac.jp:/pub/unix/mac/macutil-20b1.shar
  760.  
  761.     Use archie to find other sites.
  762.  
  763.     Here's a quick blurb on macutils from the readme.
  764.  
  765.             o hexbin - a program to convert BinHex 4.0 to MacBinary;
  766.           it also converts uuencode (and UULite) files to their
  767.           native binary format; support for .dl, .hex, and .hcx
  768.           formats (all predecessors of BinHex 4.0) also exists
  769.  
  770.             o macunpack - a program to unpack PackIt, StuffIt,
  771.           Diamond, Compactor/Compact Pro, most StuffIt Classic
  772.           and StuffIt Deluxe, DiskDoubler, Zoom and LHarc/MacLHa
  773.           archives.
  774.  
  775.           It also decodes BinHex 5.0, MacBinary, uuencode, and
  776.           UNIX compress (ie: .Z suffix) files (as well as variants
  777.           of compress implemented by various Macintosh compress
  778.           programs).
  779.  
  780.  
  781.   TRANSFERING DIRECTLY FROM A MACINTOSH
  782.  
  783.     If you are transferring a quicktime animation directly from a 
  784.     Macintosh(ftp/fetch/gator/etc), you need to use the MacBinary mode.
  785.     This will archive all three resource forks(.info,.rsrc and .data) 
  786.     into a .bin file and transfer that. You must then use "macunpack -flv"
  787.     as described above.
  788.   
  789.     If you use Binary mode(as opposed to the MacBinary mode), ONLY the 
  790.     *.data file will be transferred. This *.data file is useless without
  791.     the *.rsrc file, unless it happens to be "flattened". If you don't
  792.     absolutely know this to be true, then use the MacBinary mode and 
  793.     extract with macunpack.
  794.  
  795.  
  796.   OTHER PROGRAMS
  797.  
  798.     mcvert is also capable of extracting the *.rsrc and *.data files
  799.     form a MacBinary file(*.bin). It doesn't support all of the
  800.     archival compression formats that macunpack does and I'm not
  801.     as familiar with it. Archie should be able to find it.
  802.  
  803.   CREATING A QUICKTIME FOR EXPORT ON A MACINTOSH
  804.  
  805.     Movieconverter, part of Apple's Quicktime Starter Kit (a commercial product)
  806.     can do this.  Save the movie as BOTH "Make self-contained" and "Playable
  807.     on non-Apple computers." 
  808.  
  809.  
  810.   If you have any other questions or problems trying to run 
  811.   quicktime animation using xanim I might be able to answer
  812.   them.
  813.  
  814. ------------------------------------------------------------------------------
  815.  
  816. Mark Podlipec  podlipec@wellfleet.com
  817. http://www.portal.com/~podlipec/home.html  "The XAnim Home Page"
  818.